Repository navigation
Deprecated author and author_email for authors according to PEP621 - #3131
garvitshrma wants to merge 12 commits into
Conversation
7351b4a to
ea3d2cf
Compare
freakboy3742
left a comment
There was a problem hiding this comment.
This is a good starting point, and it looks like you've found most of the moving parts that are involved; however, it's not quite there yet.
The key detail that is missing: although we need to continue to accept author and author_email, as configuration values, the GlobalConfig and AppConfig should only be storing those values in the new "canonical" form - authors. There should be no references to author and author_email in the code, other than those necessary to process historical config files (and any time those historical settings are found, a warning should be raised).
Some of the logic that exists in parse_config is there to coerce a PEP 621 authors definition into Briefcase's definition; we need to reverse that, and coerce a historical Briefcase definition into PEP 621 form.
This may have some consequences outside the config files - for example, the create command references app.author and app.author_email when writing the app's dist_info. That reference needs to be updated to use the new app.authors. There's a couple of similar references in linux and windows packaging backends.
…ngs from docs, improved config.py to match the suggested improvement
freakboy3742
left a comment
There was a problem hiding this comment.
This is definitely headed in the right direction; a couple of minor suggestions inline.
The approach you've taken in the create method looks about right to me. I'll admit I was a little surprised by the comma-concatenation, but I've confirmed that is what the dist-info file expects, so you've done the right thing there.
The test failures you're seeing at present have two causes:
- The configuration tests are currently configured to expect to see
authorandauthor_emailin generated configurations, but with your changes, those keys are no longer generated. I flagged one of these in the review (the comment about updating the configuration to use the "current good" output); but there will be a couple of test configurations that currently defineauthorandauthor_emailthat need to be updated to defineauthorsinstead. - Coverage - you've added some new code paths that aren't tested. The coverage report is outputting:
Name Stmts Miss Branch BrPart Cover Missing
------------------------------------------------------------------------------
src/briefcase/commands/create.py 425 6 106 4 97.4% 77-78, 83-84, 88, 90
------------------------------------------------------------------------------
TOTAL 9335 6 2296 4 99.9%
So - in your code, Lines 77-78, 83-84, 88 and 90 of create.py aren't being executed by the test suite. Looking at the code, this suggests the tests that are exercising the write_dist_info method aren't passing in an authors configuration - so it's falling through to an empty list.
You'll likely also need to add some new test cases; at present, it's not possible to define an app that only has a name, or only has an email; so those branches won't be covered at present either.
The last piece that is missing is to update the references in the Linux and Windows backends to author and author_name. The Linux configurations will involve some research into how Linux system packaging tools (like RPM) express multiple authors; on Windows, there's a reference to app.author when running RCEdit. The fix there will likely be to just use the first author.
There's also the question of what happens when the user doesn't define authors, or defines an empty authors list. Strictly, PEP 621 doesn't require an author; we need to confirm if Linux and/or Windows has a problem if the author fields are omitted.
| url: str | None | ||
| author: str | None | ||
| author_email: str | None | ||
| authors: list[dict] | None |
There was a problem hiding this comment.
We can go a little tighter with this type specification:
| authors: list[dict] | None | |
| authors: list[dict[str, str]] | None |
| Update your configuration to use `authors`: | ||
|
|
||
| authors = [ | ||
| {name = "Jane Developer", email = "jane@example.com"}, |
There was a problem hiding this comment.
We're in a position to provide the actual drop-in configuration here - we know what the actual name and email configuration should be, so the error message use that text directly.
|
|
||
| # Must run before the PEP 621 merge, which removes the historical | ||
| # `author`/`author_email` settings once they have been coerced. | ||
| warn_deprecated_author_config(global_config, console) |
There was a problem hiding this comment.
Would it not make sense to keep all the deprecation code in one place? That way, when we finally finalise the deprecation, it should be a simple "delete this one function call" diff.
| "author": "First Last", | ||
| "author_email": "first@example.com", | ||
| "authors": None, |
There was a problem hiding this comment.
In general, we try to keep our test cases "up to date" - that is, reflecting a "good", current configuration; and then make special cases of the configurations needed for testing historical/migration purposes.
| "author": "First Last", | |
| "author_email": "first@example.com", | |
| "authors": None, | |
| "authors": [{"name": "First Last", "email": "first@example.com"}], |
|
One more thing to add to your testing regimen - we just received a PR that drew my attention to #2120. As part of this work, we'll need to remove the support for converting PEP 621 author names Briefcase-style author definitions in the |
e1fab06 to
6a43a87
Compare
6a43a87 to
8c4454a
Compare
|
I have addressed all the review comments, and removed the PEP 621 author conversion from the |
freakboy3742
left a comment
There was a problem hiding this comment.
We're getting closer - this has some good progress, but there's still a few piece that need attention:
- The logic for config parsing looks good now, except for one final piece of cleanup of logic from a previous pass.
- The workflow on
convertisn't quite right. It's asking the right questions if there's no author defined; but if I have a project that does have a well-formed PEP 621authorsfield, there shouldn't be a need to ask for username and email at all, and there shouldn't be a need to repeat the author definition in the extra content added to pyproject.toml by the wizard. - As currently defined, this branch will always output
authorandauthor_emailinto the template context, which will then generate a new project in the "old" author format. We'll need to modify the template context used in thenewandconvertcommands. There will be a related PR needed onbeeware/briefcase-templateto honor these new context values. - The special interpretation of "first author" in Debian, Arch and Windows packaging is worth a note in the Platform Quirks section of the respective platforms. On Windows, we should also note the interaction with
use_full_install_path(and while we're at it, I notice that the docs foruse_full_install_patharen't showing path separators for some reason...)
| url: str | None = None, | ||
| author: str | None = None, | ||
| author_email: str | None = None, | ||
| authors: list[dict] | None = None, |
There was a problem hiding this comment.
| authors: list[dict] | None = None, | |
| authors: list[dict[str, str]] | None = None, |
There was a problem hiding this comment.
This isn't really noteworthy - it's not fixing a bug, it's a change in workflow brought about by the actual feature change. We don't need an extra changenote for that.
| The `author` and `author_email` settings are deprecated in favour of | ||
| `authors`. |
There was a problem hiding this comment.
| The `author` and `author_email` settings are deprecated in favour of | |
| `authors`. | |
| The `author` and `author_email` settings have been deprecated in favour of | |
| a PEP 621 formatted `authors` setting. |
| # Coerce the historical `author`/`author_email` settings into the PEP 621 | ||
| # `authors` representation. | ||
| author = global_config.pop("author", None) | ||
| author_email = global_config.pop("author_email", None) |
There was a problem hiding this comment.
If the coercion has already occurred, this can't return anything other than None and None.
| f"# Maintainer: {app.author} <{app.author_email}>", | ||
| f'export PACKAGER="{app.author} <{app.author_email}>"', | ||
| f"# Maintainer: {maintainer(app)}", | ||
| f'export PACKAGER="{maintainer(app)}"', |
There was a problem hiding this comment.
My read of the Arch packaging guidelines is that there can be multiple # Maintainer: lines, but only one PACKAGER.
There was a problem hiding this comment.
The refactoring here is good; but the naming of the methods isn't. It's easily to visually or syntactically) confuse maintainer() and maintainers(). Suggest renaming these primary_maintainer() and secondary_maintainers().
freakboy3742
left a comment
There was a problem hiding this comment.
We're definitely getting closer; the core authors handling looks good now, we just need to finesse how the new and convert commands pass context to the template.
| """Initialize the extension with the given environment.""" | ||
| super().__init__(environment) | ||
|
|
||
| def escape_toml(obj): |
There was a problem hiding this comment.
The location here is significant - it's a part of a Cookiecutter extension. We can't remove it from this location without breaking the ability of cookiecutter templates to render content as TOML.
| f"# Maintainer: {app.author} <{app.author_email}>", | ||
| f'export PACKAGER="{app.author} <{app.author_email}>"', | ||
| f"# Maintainer: {maintainer(app)}", | ||
| f'export PACKAGER="{maintainer(app)}"', |
There was a problem hiding this comment.
The refactoring here is good; but the naming of the methods isn't. It's easily to visually or syntactically) confuse maintainer() and maintainers(). Suggest renaming these primary_maintainer() and secondary_maintainers().
|
|
||
| If an application defines the use of an environment manager (using the [`env_manager`][] setting), and Docker is used to build the application, the environment manager will be ignored, and raw `pip` installs will be used. | ||
|
|
||
| ### Only the first author is used as the package maintainer |
There was a problem hiding this comment.
| ### Only the first author is used as the package maintainer | |
| ### Interpreting authors as package maintainers |
|
|
||
| For example, consider an installer that creates a `data` folder in the app, containing 2 files `a.dat` and `b.dat`. The MSI installer has a post-installation script that deletes `b.dat`, and adds `c.dat`. When the uninstallation process is executed, registry entries for `data/b.dat` and `data` will remain in the registry. A well-behaved app should *not* delete content that the MSI app installed; and it should not leave content in locations that would prevent the MSI from removing content that the MSI installed. | ||
|
|
||
| ### Only the first author is used as the company name |
There was a problem hiding this comment.
| ### Only the first author is used as the company name | |
| ### Interpreting authors as product owners |
| An app can have more than one author. However, a Windows app has a single `CompanyName` property, so it uses the *first* author listed in the app's [`authors`][] setting. | ||
|
|
||
| If [`use_full_install_path`][] is turned on (which is the default), the app is installed into a folder named after `CompanyName`. This means that changing the order of the authors will also change where the app is installed. |
There was a problem hiding this comment.
| An app can have more than one author. However, a Windows app has a single `CompanyName` property, so it uses the *first* author listed in the app's [`authors`][] setting. | |
| If [`use_full_install_path`][] is turned on (which is the default), the app is installed into a folder named after `CompanyName`. This means that changing the order of the authors will also change where the app is installed. | |
| An app can have more than one author. However, when [`use_full_install_path`][] is enabled (as it is by default), a Windows app is installed in folder matching the company that produced the app. Briefcase will use the name of the first author listed in the app's [`authors`][] setting as the company name. |
| "authors": authors_toml(authors), | ||
| "copyright_holder": copyright_holder(authors), |
There was a problem hiding this comment.
We shouldn't be passing rendered TOML to the template. We pass data to the template, and the template renders that data.
The new and convert commands now provide the app's authors as a pep621 context dictionary, leaving the template to render them. The toml_inline_table and lexical_join cookiecutter filters have been added so that a template can generate the TOML and copyright notice forms of that data.
I have deprecated the
authorandauthor_emailsettings in favour ofauthors, following the PEP 621 configuration. A warning is now printed when a user uses the old settings (authorandauthor_email). I have also added a note in the docs mentioning the deprecation of the two old settings. I have addedauthorsas a list in every place.authorsnow contains both the author name and email.Briefcase now follows the PEP 621 guidelines for the author settings.
Refs #1235
PR Checklist:
Assisted-by: Claude Opus 5